
MacPerl Help -- Specific features of MacPerl

                                               version: 5.0
                                               created: 09/05/1994 {06:36:17 am}
                                           last update: 04/01/2003 {11:55:55 AM}

Author: Matthias Neeracher

This file describes differences between MacPerl and a typical Unix perl
implementation.  Much of this information can also be found at the end of
PerlHelp.  If you have 411, search for PerlMacintoshExtensions.


	  	Table Of Contents


"# 1. VARIA"
"# 2. SOCKETS"
"# 3. ADDITIONAL FUNCTIONS AVAILABLE IN MACPERL"

<<floatNamedMarks>>


	  	1. VARIA


"\n" on a Mac means ASCII 13, as opposed to Unix, where it means ASCII 10

Pathnames are specified as:

	volume:folder:file              for absolute pathnames
	:folder:file                    for relative pathnames
	:file                           for relative pathnames
	file                            for relative pathnames

MacPerl has a limited capability to handle constructs like `command` or
open(F, "|command"), if you are the lucky owner of ToolServer. 
Additionally, whether you have toolserver or not, `pwd` and `Directory`
(case is significant) always return the current directory, followed by a
newline.


	  	2. SOCKETS


MacPerl has more Socket families than Unix Perl.  Additionally, there is a
call choose() to allow the user to interactively specify addresses or file
names.  As there are lots of rather complicated data types, there is a
library header "GUSI.ph" which defines packing/unpacking procedures.

Choose() is called as follows:

	&MacPerl'Choose(DOMAIN,TYPE,PROMPT,CONSTRAINT,FLAGS,DEFAULT)
	&MacPerl'Choose(DOMAIN,TYPE,PROMPT,CONSTRAINT,FLAGS)
	&MacPerl'Choose(DOMAIN,TYPE,PROMPT,CONSTRAINT)
	&MacPerl'Choose(DOMAIN,TYPE,PROMPT)

Puts up a modal dialog prompting the user to choose an address.  DOMAIN
specifies the communication domain, like for socket().  TYPE may be used by
future communication domains to further differentiate within a domain, but
is ignored by current domains.  PROMPT is a message that will appear in the
dialog.  CONSTRAINT may be set to a suitable packed value to restrict the
types of acceptable addresses.

Examples:

	require "GUSI.ph";

	$file = 
	   MacPerl'Choose(
		  &GUSI'AF_FILE, 0, "", 
		  &GUSI'pack_sa_constr_file("OBJ ", "TEXT"));
					  
				  Return the full pathname of an existing text
				  or MPW object file.

	$dir = &MacPerl'Choose(&GUSI'AF_FILE, 0, "", "", &GUSI'CHOOSE_DIR);

				  Return the full pathname of an existing directory.
					  
	$file = 
	   &MacPerl'Choose(
		  &GUSI'AF_FILE, 0, "", "", 
		  &GUSI'CHOOSE_NEW + &GUSI'CHOOSE_DEFAULT, "yo");

Return the pathname of a new file to be created.
                                     
Socket families are:

Internet:

Packing addresses:      &GUSI'pack_sockaddr_in(family, address, port)
Unpacking addresses:    (family, address, port) = &GUSI'unpack_sockaddr_in(addr)
Choose:                 Not available.

Unix:

Packing addresses:      &GUSI'pack_sockaddr_un(family, path)
Unpacking addresses:    (family, path) = &GUSI'unpack_sockaddr_un(addr)
Choose:                 choose(&GUSI'AF_UNIX, 0, "", "", 0, "");
                        looks up an existing address.
                        choose(
                            &GUSI'AF_UNIX, 0, "Yes ?", "", 
                            &GUSI'CHOOSE_NEW + &GUSI'CHOOSE_DEFAULT, "yo");
                        creates a new address.
                        No constraints may be specified.

Appletalk (ADSP):

Packing addresses:      &GUSI'pack_sockaddr_atlk(family, net, node, socket)     (numerical)
                            &GUSI'pack_sockaddr_atlk_sym(family, obj, type, zone)   (symbolic)
Unpacking addresses:    (family, net, node, socket) = &GUSI'unpack_sockaddr_atlk(addr)
                            (family, obj, type, zone) = &GUSI'unpack_sockaddr_atlk_sym(addr)
Choose:                 choose(&GUSI'AF_APPLETALK, 0, "Eh ?", 
                                &GUSI'pack_sa_constr_atlk("LaserWriter", "GorillaWriter"),
                                0, "");
                        looks up an existing address.
                        New addresses may not currently be created with choose.

PPC Toolbox:

Packing addresses:      &GUSI'pack_sockaddr_ppc(family, type, name, porttype)
Unpacking addresses:    Not available.
Choose:                 choose(&GUSI'AF_PPC, 0, "Eh ?", 
                                &GUSI'pack_sa_constr_ppc("Gonkulator"), 0, "");
                        looks up an existing address.
                        New addresses may not currently be created with choose.


	  	3. ADDITIONAL FUNCTIONS AVAILABLE IN MACPERL


	&MacPerl'Answer(PROMPT)
	&MacPerl'Answer(PROMPT,BUTTON1)
	&MacPerl'Answer(PROMPT,BUTTON1,BUTTON2)
	&MacPerl'Answer(PROMPT,BUTTON1,BUTTON2,BUTTON3)

Presents to the user a dialog with 1, 2, or 3 buttons. 
          
Examples:
          
	&MacPerl'Answer("Nunc et in hora mortis nostrae", "Amen");
                          
always returns 0.
                        
	&MacPerl'Answer("I refuse");
      
is equivalent to &MacPerl'Answer("I refuse", "OK");
      
	&MacPerl'Answer("Delete hard disk ?", "OK", "Cancel");
              
returns 1 for OK, 0 for Cancel

	&MacPerl'Answer("Overwrite existig file", "Overwrite", "Skip", "Cancel");
          
returns 2 for Overwrite, 1 for Skip, 0 for Cancel
                            
	&MacPerl'Ask(PROMPT, DEFAULT)
	&MacPerl'Ask(PROMPT)

Asks the user for a string.  A default value may be given.  Returns undef
if the dialog is cancelled.
          
Example:
          
	$phone = &&MacPerl'Ask("Enter your phone number:");
	$name = &&MacPerl'Ask("Enter your first name", "Bruce");
	
(Useful for Australian database applications)
                            
	&MacPerl'Pick(PROMPT, VALUES)

Asks the user to pick a choice from a list.  VALUES is a list of choices. 
Returns undef if the dialog is cancelled.
          
Examples:
          
	$color = &MacPerl'Pick("What's your favorite color baby ?", "Red", "Green", "Gold");
	
	&MacPerl'SetFileInfo(CREATOR,TYPE,FILE...)

Changes the file types and creators of the file(s).

Examples:

	&MacPerl'SetFileInfo("MPS ", "TEXT", yin, yang);

Turn yin and yang into MPW text files

	&MacPerl'GetFileInfo(FILE)

In scalar context, returns the file type.  In array context, returns
(creator,type).

Examples:

	&MacPerl'GetFileInfo(yin);

Returns "TEXT" or ("MPS ", "TEXT").

	&MacPerl'DoAppleScript(SCRIPT)

Execute an AppleScript script.
         
Example:
         
	&MacPerl'DoAppleScript(<<END_SCRIPT);
	tell application "MacPerl"
	make new Window
	copy "Inserting text the hard way." to character 1 of front Window
	end tell
	END_SCRIPT
	
	&MacPerl'Reply(ANSWER)

Reply to current DoScript request.  Useful if you are calling Perl scripts
from other applications.
         
	&MacPerl'Quit(LEVEL)

If Level is 0, don't quit after ending the script.  If 1, quit if running
under a runtime version, if 2, always quit.

	&MacPerl'LoadExternals(LIBFILE)

Load XCMD and XFCN extensions contained in file LIBFILE, which is searched
along the same path as it would be for a require.  The extensions are made
accessible in the current package, unless they conatin an explicit package
name.

	&MacPerl'DebugExternals(DEBUGLEVEL)

If DEBUGLEVEL is 0, don't print any debug information for XCMDs and XFCNs. 
If 1, print information for unimplemented callbacks.  If 2, print
informations for all callbacks.

	&MacPerl'FAccess(FILE, CMD, ARGS)

When called from the tool, manipulate various information of files.  To get
the command constants, it's convenient to require "FAccess.ph".

	$TAB = &MacPerl'FAccess(FILE, &F_GTABINFO)
	&MacPerl'FAccess(FILE, &F_STABINFO, TAB)

Manipulate tabulator setting (in spaces per tab).
         
	($FONTNAME, $FONTSIZE) = &MacPerl'FAccess(FILE, &F_GFONTINFO)
	$FONTNUM = &MacPerl'FAccess(FILE, &F_GFONTINFO)
	&MacPerl'FAccess(FILE, &F_SFONTINFO, FONT [, SIZE])

Manipulate font and size information.  Both font names and font numbers are
accepted for F_SFONTINFO; F_GFONTINFO returns a font name in an array
context, a font number in a scalar context.
         
	($STARTSEL, $ENDSEL, $DISPLAYTOP) = &MacPerl'FAccess(FILE, &F_GSELINFO)
	$STARTSEL = &MacPerl'FAccess(FILE, &F_GSELINFO)
	&MacPerl'FAccess(FILE, &F_SSELINFO, $STARTSEL, $ENDSEL [, $DISPLAYTOP])

Manipulate the MPW selection of a file.
         
	($LEFT, $TOP, $RIGHT, $BOTTOM) = &MacPerl'FAccess(FILE, &F_GWININFO)
	$TOP = &MacPerl'FAccess(FILE, &F_GWININFO)
	&MacPerl'FAccess(FILE, &F_SWININFO, LEFT, TOP [, RIGHT, BOTTOM])

Manipulate the window position.

